home *** CD-ROM | disk | FTP | other *** search
/ Aminet 12 / Aminet 12 (1996)(GTI - Schatztruhe)[!][Jun 1996].iso / Aminet / dev / lang / HeliOS4.lha / helios_demo_disk4 / docs / userinterface / HelpSystems.doc < prev    next >
Encoding:
Text File  |  1995-07-10  |  15.1 KB  |  452 lines
  1.  
  2. *******************
  3. User Interface Help
  4. *******************
  5.  
  6. Brief on line help is available for ALL menu and gadget functions, even
  7. within sub-systems of the program e.g. Find/Replace, Colour Selection, and
  8. the Debugger.
  9.  
  10. This help can be obtained by entering HELP mode and then selecting any
  11. menu or control button.
  12.  
  13. To enter HELP mode, either:
  14.  
  15. 1. Select the menu Help option.
  16.  
  17. 2. Press the <Help> key.
  18.  
  19. 3. Press the on screen HELP gadget (if it is visible).
  20.  
  21. To get help on "hidden" control panels such as the "debug control panel",
  22. or the "colour control panel", simply activate the panel and then press
  23. the <Help> key to enter HELP mode.
  24.  
  25.  
  26. ***************
  27. Vocabulary HELP
  28. ***************
  29.  
  30. HeliOS has very comprehensive user-configurable Vocabulary Help, and
  31. this can be set up either very simply or in relatively complex ways,
  32. depending on how you wish the help system to function.
  33.  
  34. The basic idea of all HeliOS Vocabulary Help is that you place the text
  35. cursor of the HeliOS interpreter or editor over any word and then press
  36. a key to get Help on that word or run an example program.
  37.  
  38. The HeliOS Vocabulary Help system uses a special file called a "Vocabulary
  39. Help" file which acts as the source of Vocabulary Help textual information
  40. and also as a configuration file.
  41.  
  42. In order to activate the advanced Vocabulary Help system it is necessary
  43. to use HeliOS macro key definitions, and you should read the document file
  44. called "HeliOS_Macro_Commands.Doc" for more details on this.
  45.  
  46.  
  47. *******************************
  48. A note on Vocabulary Help files
  49. *******************************
  50.  
  51. Vocabulary Help files are ordinary ASCII files and can be edited in any
  52. text editor (such as the HeliOS editors).
  53.  
  54. All of the many features of the HeliOS help system are controlled using
  55. these specially formatted Vocabulary Help text files.
  56.  
  57. Only one Vocabulary Help file can be active at any time, but there are
  58. provisions for swapping or modifying this file as required.
  59.  
  60. HeliOS can be set up to automatically load any file as a Vocabulary Help
  61. file at system startup time (See "InitialSetup.doc")
  62.  
  63. Alternatively, there are menu options for loading different Vocabulary
  64. Help files, and there is a HeliOS command word, called "VHELP", which
  65. allows direct access to, and manipulation of, Vocabulary Help files.
  66.  
  67. A Vocabulary Help file can contain the following elements:
  68.  
  69. 1. Plain ASCII text which can act as a commentary on, or description of,
  70.    the "operational" contents of the Vocabulary Help file.
  71.  
  72. 2. Help texts (one or two pages) which can be associated with any word.
  73.  
  74. 3. Three sets of specially encoded information which can be associated
  75.    with any word.  This information can specify such things as paths
  76.    and filenames to example programs or extended help files.
  77.  
  78. 4. A command file name which allows dynamic pre-processing of the help
  79.    information by running a user defined HeliOS program whenever the
  80.    Vocabulary Help file is loaded.
  81.  
  82.  
  83. ******************************************************
  84. What you can do with the HeliOS Vocabulary Help system
  85. ******************************************************
  86.  
  87. The basic idea of the HeliOS help system is that the cursor can be placed
  88. over any word within the text in one of the HeliOS editors, or the HeliOS
  89. interpreter command line, and then help can be called up for that word.
  90.  
  91. The interesting thing is that the help which is called up can have a wide
  92. variety of forms, and is fully user definable.
  93.  
  94. You can, with a single user-defined keypress, do things like this:
  95.  
  96. * Present one or two pages of help text in a pop-up requester.
  97.  
  98. * Display a help file in an external text reader.
  99.  
  100. * Display and edit on-line a help file in an external text editor.
  101.  
  102. * Display and edit on-line a help file in one of the HeliOS editors.
  103.  
  104. * Load into a HeliOS editor a special comprehensive HeliOS help file
  105.   and jump to all references to the specified word.
  106.  
  107. * Load into a HeliOS editor, for viewing or editing, an example HeliOS
  108.   program file.
  109.  
  110. * Run an example HeliOS program using the stand-alone HeliOS compiler.
  111.  
  112. * Load and run an example HeliOS program using the internal interpreter.
  113.  
  114. * Load and edit a Vocabulary Help file.
  115.  
  116. * Change or modify the existing on-line Vocabulary Help buffer.
  117.  
  118. ...and much more.
  119.  
  120. In fact the whole system is so configurable that you can virtually define
  121. your own actions.
  122.  
  123.  
  124. **********************
  125. Simple Vocabulary Help
  126. **********************
  127.  
  128. There is a user definable vocabulary help which, at its simplest level,
  129. brings up short one or two page help texts on the word under the cursor.
  130.  
  131. The help display is deliberately kept small, with the intention of reducing
  132. verbosity and forcing the help to be short and easily assimilable.  The
  133. idea is not to provide an essay but short and precise useful information.
  134.  
  135. Single target words are matched with the word under the cursor when
  136. vocabulary help is invoked, and the associated text in the help file is
  137. presented in the HeliOS help display.
  138.  
  139. Vocabulary help can consist of up to TWO pages.  The HeliOS software will
  140. auto-check and inform the user if a second page of help is available.
  141.  
  142. The target word matching is NOT case sensitive, and to select the simple
  143. Vocabulary Help function just place the cursor within the word on which
  144. you want help, and either
  145.  
  146. 1. Select the menu option.
  147.  
  148. 2. Press <Ctrl>+<Help> or <Shift>+<Help> on the keyboard.
  149.  
  150. 3. Hold down <Ctrl> or <Shift> while pressing the HELP screen gadget.
  151.  
  152. The user definable help file is in simple ASCII format, and the startup
  153. default is usually read from a file called "HeliOS_VocabularyHelp" in the
  154. "S:" directory (or the HELIOS: directory if defined).
  155.  
  156. See the documentaion on InitialSetup for details on setting up a default
  157. file to be auto-loaded at startup.
  158.  
  159. Note that Vocabulary Help files can be edited in any ASCII text editor.
  160.  
  161. You may create several help files if you wish, and load each one as
  162. required, but only one Vocabulary Help file may be loaded at any time.
  163.  
  164. The example help file provided itself contains full instructions for
  165. user additions, but below is a brief description of how to create, or
  166. add to, a simple Vocabulary Help file.
  167.  
  168.  
  169. ************************************************
  170. Creating or Editing Simple Vocabulary Help files
  171. ************************************************
  172.  
  173. The text below describes the simple on-line Vocabulary Help file format.
  174.  
  175. More complex additions can be built into the file for specialised
  176. sophisticated help systems, as described in the HeliOS_Macro_Command
  177. doc file, but we discuss here the most basic standard help file format.
  178.  
  179. Each "Help Entry" in the file must be of the following format:
  180.  
  181. Firstly, a line starting with "{{" containing the target word....
  182.  
  183. {{TARGETWORD&
  184. ^^
  185. This signifies the start of an entry, and should be followed by the
  186. target word....
  187.  
  188. {{TARGETWORD&
  189.   ^^^^^^^^^^
  190. This target word will be matched to the word under the cursor when
  191. you invoke vocabulary help.  Only the single SPACE delimited word under
  192. the cursor will be used for matching purposes, so your target word should
  193. also be a single word without spaces.
  194.  
  195. {{TARGETWORD&
  196.             ^
  197. This "&" signifies the end of a line of the first page of help text, and
  198. should be placed immediately after the target word and at the end of each
  199. subsequent "first page" line.
  200.  
  201. A "&" as the first character on any line will create a blank line in the
  202. help text "first page".
  203.  
  204. e.g.
  205.  
  206. &                                <- A blank line to start with
  207. First line of help text. &
  208. Second line of help text.&
  209. Third line of help text. &
  210.                          &       <- Another blank line - note that the "&"
  211. etc.                                can be anywhere on the line
  212. etc.
  213.  
  214. Finally, to end each entry...
  215.  
  216. }}
  217. ^^
  218. This signifies the end of an entry, and should be placed after the
  219. last line of the entry. (After the last end-of-line "&" character).
  220.  
  221.  
  222. An complete single page example entry might be something like:
  223.  
  224. {{TARGETWORD&
  225. &
  226. First line of help text.&
  227. &
  228. Second line of help text.&
  229. &
  230. Third line of help text.&
  231. }}
  232.  
  233.  
  234. Using the "second page":
  235.  
  236. The '&' character denotes the end of a help text "first page" line, but you
  237. are free to enter "second page" text after this character on the same line.
  238. This text (everything after the '&') will be presented as a second page of
  239. help by the user pressing the HELP key.
  240.  
  241. e.g.
  242.  
  243. {{TARGETWORD&
  244.                          &
  245. First line of help text. &  This is a comment, or note, and
  246.                          &  will be displayed when the user
  247. Second line of help text.&  presses HELP.
  248.                          &
  249. Third line of help text. &
  250. }}
  251.  
  252. Note that the starting position of "second page" text is determined by
  253. the number of spaces AFTER the "&" character.
  254.  
  255.  
  256. Constraints:
  257.  
  258. There are a few constraints imposed by the limits of the help display.
  259.  
  260. The maximum displayable line length is 47 characters.
  261.  
  262. Lines longer than 47 characters will be truncated to 47 charatcters
  263. when displayed on screen.
  264.  
  265. The maximum number of lines per entry, not including the target word
  266. itself, is 7 lines.
  267.  
  268. Entries having more than 7 lines will be truncated when displayed
  269. and only 7 lines will be shown.
  270.  
  271. The limits mentioned above (of 47 characters and 7 lines) will be
  272. automatically imposed when the entry is displayed on screen.  It is
  273. perfectly safe to exceed these limits within the help file, but any
  274. extra text will not be displayed.
  275.  
  276.  
  277. ************************
  278. Advanced Vocabulary Help
  279. ************************
  280.  
  281. The HeliOS Vocabulary Help system can be expanded by a special set of words
  282. which are used in conjunction with macro keys.
  283.  
  284. You can set up interactive help systems which run example programs and
  285. allow you to access, browse, and edit on-line full detailed help files.
  286.  
  287. Please see the file:
  288.  
  289.  HeliOS:Docs/UserInterface/HeliOS_Macro_Commands.Doc
  290.  
  291. for details on how the macro key interface commands work.
  292.  
  293. The information given in that file is vital to the operation of Vocabulary
  294. Help, and is MUST be read in conjunction with the supplementary information
  295. given here.
  296.  
  297. The idea here is that special macro key commands can be used to run HeliOS
  298. programs and access help information as specified by various file paths
  299. encoded into the Vocabulary Help file and associated with a target word.
  300.  
  301.  
  302. ************************************************
  303. Advanced control over the Vocabulary Help System
  304. ************************************************
  305.  
  306. ***********************
  307. Using the VHELP command
  308. ***********************
  309.  
  310. The above mentioned HeliOS_Macro_Command file, and the Dictionary,doc,
  311. both contain the definition of a word called VHELP, which allows full
  312. access to the HeliOS Vocabulary Help buffer.
  313.  
  314. Using VHELP you can modify or remove the existing HeliOS help information
  315. residing in the active Vocabulary Help file buffer.
  316.  
  317. In effect, using VHELP, you can dynamically change and reprogram the
  318. on-line Help file in any way you choose.
  319.  
  320.  
  321. ***********************************
  322. Vocabulary Help startup programming
  323. ***********************************
  324.  
  325. As well as using the VHELP command, there is another way in which you
  326. can reprogram the on-line Vocabulary Help.
  327.  
  328. This is by setting up a Vocabulary Help startup command, which is a
  329. HeliOS program whose file name can be specified in a Vocabulary Help
  330. file and which is run as the Vocabulary Help file itself is installed.
  331.  
  332. In order to specify this startup command program the Vocabulary Help
  333. file can have a special line at the beginning containing the filename
  334. of the HeliOS program file to be be run at Vocabulary Help load time.
  335.  
  336. The special command line looks like this:
  337.  
  338. {StartCmd}{HeliOS:VHelpAction}
  339.            ^^^^^^^^^^^^^^^^^^
  340.            Any valid file path
  341.  
  342. This line, if present, must be placed within the first 400 bytes of the
  343. Vocabulary Help file.
  344.  
  345. If the line is present, the file specified in the example as:
  346.  
  347. HeliOS:VHelpAction
  348.  
  349. will be executed as soon as the Vocabulary Help file has been loaded.
  350.  
  351. Note that the startup command file is a normal HeliOS source code file,
  352. and will be run by the normal HeliOS interpreter, with the only special
  353. provisos that:
  354.  
  355. 1. No error messages will be given.
  356.  
  357. 2. The program must NOT issue any text output.
  358.  
  359.  
  360. Note that if the following line is given:
  361.  
  362. {StartCmd}{0}
  363.  
  364. no help file will be loaded.
  365.  
  366. The "StartCmd" line may also be omitted to achieve the same effect.
  367.  
  368.  
  369. *************************************************************
  370. Stack parameters for the Vocabulary Help startup command file
  371. *************************************************************
  372.  
  373. When the special startup program is launched, HeliOS will place on the
  374. stack two useful parameters:
  375.  
  376. VHelpBuffer(l)  VHelpBuffSize(l)
  377.   2nd on stack    Top of stack
  378.  
  379. which allow you instant access to the internal Vocabulary Help buffer.
  380.  
  381. When the program completes there are further options for you to specify
  382. parameters on the stack telling HeliOS to do various things.
  383.  
  384. Basically the program must return two parameters, similar to those
  385. which it received at startup:
  386.  
  387. VHelpBuffer(l)  VHelpBuffSize(l)
  388.  
  389. If these are exactly the same as it received at startup, HeliOS will
  390. carry on and use the existing Vocabulary Help buffer.
  391.  
  392. If either of the returned parameters is null, HeliOS will deallocate
  393. the existing Vocabulary Help buffer and switch off Vocabulary Help.
  394.  
  395. If both of the returned parameters are non-null the new parameters
  396. will be used by HeliOS to define a new internal Vocabulary Help buffer,
  397. and the old buffer will be automatically deallocated.
  398.  
  399. The startup command file can thus generate its own Vocabulary Help if
  400. required, or do various interesting things to the existing file.
  401.  
  402. For example:
  403.  
  404. The Vocabulary Help startup program could, if you wish, deallocate the
  405. existing Vocabulary Help buffer using a code line like this:
  406.  
  407. DDROP FREEMEMORY      \ Drop Buffsize and free buffer
  408.  
  409. Note that the help buffer can be deallocated simply using FREEMEMORY.
  410.  
  411. Then the startup program might perhaps concatenate several Help files
  412. together into a new big buffer, and then it could say:
  413.  
  414. MyNewVHelpBuff MyNewVHelpBuffSize
  415.  
  416. before quitting.
  417.  
  418. This, along with the facility to perform any programmed manipulation you
  419. choose, allows very flexible user-control of the Vocabulary Help system.
  420.  
  421.  
  422. ***************************************************************
  423. A summary of the Vocabulary Help startup command program useage
  424. ***************************************************************
  425.  
  426. * If this command does not change stack parameters, the existing preloaded
  427.   Vocabulary Help file will be retained.
  428.  
  429. * If this command does change stack parameters, the returned values will
  430.   be used as those for the internal VHelp file unless either of them is
  431.   null.
  432.  
  433. * If this command returns a null parameter HeliOS will deallocate the
  434.   existing on-line Vocabulary Help file.
  435.  
  436. * If this command does return changed stack parameters, it might be best
  437.   if the program itself were to deallocate the old Help buffer before
  438.   allocating a new one.  However, the HeliOS system will also double
  439.   check and close the old buffer if it is still left open.
  440.  
  441.  
  442. ********************************************************************
  443. Using advanced Vocabulary Help features employing macro command keys
  444. ********************************************************************
  445.  
  446. Please read the file "HeliOS_Macro_Commands.Doc" for details on this.
  447.  
  448.  
  449. ***********************************************************************
  450. End
  451. ***********************************************************************
  452.